from zope.interface import Interface, Attribute

class IObject(Interface):
    """This is an abstract base class and cannot be used directly in a KML file.
    """

    id = Attribute(u"id", "Allows unique identification of a KML element. "
        "The id attribute must be assigned if the <Update> mechanism is to be used.")

    targetId = Attribute(u"targetId", "Used to reference objects that have "
        "already been loaded into Google Earth.")


class IFeature(IObject):
    """This is an abstract element and cannot be used directly in a KML file.
    """

    name = Attribute(u"name", "User-defined text displayed in the 3D viewer "
        "as the label for the object.")

    visibility = Attribute(u"visibility", "Boolean value (default=1). Specifies "
        "whether the feature is drawn in the 3D viewer when it is initially loaded."
        "In order for a feature to be visible, the <visibility> tag of all its "
        "ancestors must also be set to 1. In the Google Earth List View, each "
        "Feature has a checkbox that allows the user to control visibility of "
        "the Feature.")

    open = Attribute(u"open", "Boolean value (default=1). Specifies whether a "
        "Folder appears closed or open when first loaded into the Places panel. "
        "0=collapsed, 1=expanded.")

    address = Attribute(u"address", "A string value representing an "
        "unstructured address written as a standard street, city, state address"
        ", and/or as a postal code. You can use the <address> tag to specify "
        "the location of a point instead of using latitude and longitude coordinates.")

    AddressDetails = Attribute(u'AddressDetails', "A structured address, "
        "formatted as xAL, or eXtensible Address Language, an international "
        "standard for address formatting. <AddressDetails> is used by KML for"
        "geocoding in Google Maps only.")

    phoneNumber = Attribute(u"phoneNumber", "A string value representing a "
        "telephone number. This element is used by Google Maps Mobile only.")

    Snippet = Attribute(u"Snippet", "A short description of the feature. In "
        "Google Earth, this description is displayed in the Places panel under "
        "the name of the feature. If a Snippet is not supplied, the first two "
        "lines of the <description> are used. In Google Earth, if a Placemark "
        "contains both a description and a Snippet, the <Snippet> appears "
        "beneath the Placemark in the Places panel, and the <description> "
        "appears in the Placemark's description balloon. This tag does not "
        "support HTML markup. <Snippet> has a maxLines attribute, an integer "
        "that specifies the maximum number of lines to display. Default for "
        "maxLines is 2.")

    description = Attribute(u"description", "User-supplied text that appears "
        "in the description balloon when the user clicks on either the feature "
        "name in the Places panel or the Placemark icon in the 3D viewer. This "
        "text also appears beneath the feature name in the Places panel if no "
        "<Snippet> tag is specified for the feature.")

    LookAt = Attribute(u"LookAt", "Defines a camera viewpoint associated with "
        "any element derived from Feature.")

    styleUrl = Attribute(u"styleUrl", "URI (a URI equals [URL]#ID) of a "
        "<Style> or <StyleMap> defined in a Document. If the style is in the "
        "same file, use a # reference. If the style is defined in an external "
        "file, use a full URL along with # referencing.")

    StyleSelector = Attribute(u"StyleSelector", "One or more Styles and "
        "StyleMaps can be defined to customize the appearance of any element "
        "derived from Feature or of the Geometry in a Placemark.")

    Region = Attribute(u"Region", "Features and geometry associated with a "
        "Region are drawn only when the Region is active.")

class IPlacemark(IFeature):
    """A Placemark is a Feature with associated Geometry. In Google Earth, a
    Placemark appears as a list item in the Places panel. A Placemark with a 
    Point has an icon associated with it that marks a point on the earth in 
    the 3D viewer. (In the Google Earth 3D viewer, a Point Placemark is the
    only object you can click or roll over. Other Geometry objects do not 
    have an icon in the 3D viewer. To give the user something to click, you 
    would need to add a Point to the Polygon.)"""

    geometry = Attribute(u"Returns one <Geometry> element, and None if no"
        "Geometry is associated.")

class IGeometry(IObject):
    """This is an abstract element and cannot be used directly in a KML file.
    It provides a placeholderobject for all derived Geometry objects."""

    extrude = Attribute(u"extrude", "Boolean value (default=0). Specifies "
        "whether to connect the geometric primitive (icon, line, polygon) to "
        "the ground. Extrusion requires that the geometry's <altitudeMode> be "
        "either relativeToGround or absolute and that within the <coordinates> "
        "element, the altitude component be greater than 0 (that is, in the air).")

    tessellate = Attribute(u"tessellate", "Boolean value (default=0). Specifies "
        "whether to allow lines and paths to follow the terrain. This "
        "specification applies only to LineStrings (paths) and LinearRings "
        "(polygons) that have an <altitudeMode> of clampToGround. Very long "
        "lines should enable tessellation so that they follow the curvature of "
        "the earth (otherwise, they may go underground and be hidden).")

    altitudeMode = Attribute(u"altitudeMode", "Specifies how altitude "
        "components in the <coordinates> element are interpreted. Possible "
        "values are: clampToGround - (default) Indicates to ignore an altitude" 
        "specification (for example, in the <coordinates> tag). "
        "RelativeToGround - Sets the altitude of the element relative to the "
        "actual ground elevation of a particular location. Absolute - Sets "
        "the altitude of the coordinate relative to sea level, regardless of "
        "the actual elevation of the terrain beneath the element. For example, "
        "if you set the altitude of a coordinate to 10 meters with an absolute "
        "altitude mode, the icon of a point placemark will appear to be at "
        "ground level if the terrain beneath is also 10 meters above sea level."
        " If the terrain is 3 meters above sea level, the placemark will appear"
        " elevated above the terrain by 7 meters. A typical use of this mode is "
        "for aircraft placement.""")


class IPoint(IGeometry):
    """ A geographic location defined by longitude, latitude, and (optional)
        altitude. When a Point is contained by a Placemark, the point itself
        determines the position of the Placemark's name and icon. When a Point is
        extruded, it is connected to the ground with a line. This "tether" uses
        the current LineStyle."""

    coordinates = Attribute(u"coordinates", "A single tuple consisting of "
        "floating point values for longitude, latitude, and altitude (in that "
        "order). Longitude and latitude values are in degrees, where\n"
        "* longitude ≥ -180 and <= 180\n"
        "* latitude ≥ -90 and ≤ 90\n"
        "* altitude values (optional) are in meters above sea level.""")


class ILineString(IGeometry):
    """ Defines a connected set of line segments. Use <LineStyle> to specify
        the color, color mode, and width of the line. When a LineString is
        extruded, the line is extended to the ground, forming a polygon that
        looks somewhat like a wall. For extruded LineStrings, the line itself
        uses the current LineStyle, and the extrusion uses the current PolyStyle."""

    coordinates = Attribute(u"coordinates", "Two or more coordinate tuples, "
        "each consisting of floating point values for longitude, latitude, and "
        "altitude. The altitude component is optional. Insert a space between "
        "tuples. Do not include spaces within a tuple.")


class ILinearRing(IGeometry):
    """ Defines a closed line string, typically the outer boundary of a
        Polygon. Optionally, a LinearRing can also be used as the inner
        boundary of a Polygon to create holes in the Polygon."""

    coordinates = Attribute(u"coordinates", "Four or more tuples, each "
        "consisting of floating point values for longitude, latitude, and "
        "altitude. The altitude component is optional. Do not include spaces "
        "within a tuple. The last coordinate must be the same as the first "
        "coordinate. Coordinates are expressed in decimal degrees only.")


class IPolygon(IGeometry):
    """ A Polygon is defined by an outer boundary and 0 or more inner boundaries
        The boundaries, in turn, are defined by LinearRings. When a Polygon is
        extruded, its boundaries are connected to the ground to form additional
        polygons, which gives the appearance of a building. When a Polygon is
        extruded, each point is extruded individually. Extruded Polygons use
        <PolyStyle> for their color, color mode, and fill."""

    outerBoundaryIs = Attribute(u"outerBoundaryIs", "Contains a <LinearRing> element.")

    innerBoundaryIs = Attribute(u"innerBoundaryIs", "Contains a <LinearRing> element.")


class IMultiGeometry(Interface):
    """ A container for one or more geometry primitives associated with the same
        feature."""

class IModel(IGeometry):
    """ A 3D object described in a Collada file (referenced in the <Link> tag).
        Collada files have a .dae file extension. Models are created in their
        own coordinate space and then located, positioned, and scaled in Google Earth."""

    Location = Attribute(u"Location", "Specifies the exact coordinates of "
        "the Model's origin in latitude, longitude, and altitude. Latitude and "
        "longitude measurements are standard lat-lon projection with WGS84 "
        "datum. Google Earth uses simple cylindrical projection, which is a "
        "simple map projection where the meridians and parallels are equidistant "
        "parallel lines, with the two sets crossing at right angles. Altitude is "
        "distance above the earth's surface, in meters, and is interpreted "
        "according to <altitudeMode>.")

    Orientation = Attribute(u"Orientation", "Describes rotation of a 3D model's "
        "coordinate system to position the object in Google Earth.")

    Scale = Attribute(u"Scale", "Scales a model along the x, y, and z axes "
        "in the model's coordinate space.")

    Link = Attribute(u"Link", "Specifies the file to load and optional refresh "
        "parameters.")
